Overload docs #3159

gvanrossum · 2017-04-12T17:38:58Z

This is based on PR #2792 by @jkleint. It documents the feature added in PR @2603 by @sixolet.

@sixolet, @ilevkivskyi, @pkch -- any comments on this version?

The docs say `@override` doesn't work in user code, but it seems to work in mypy 0.470. The update may be waiting on #2603, but that PR does not seem to include doc updates, so feel free to put this patch in that PR.

sixolet

Thank you. I especially like the __getitem__ motivation, because it's a thing the user is quite likely to run into, unlike trying to redefine abs.

My commentary is mostly picky wordsmithing stuff, and as such is a matter of judgement. Take that of it which seems to make the writing clearer, and leave the rest.

sixolet · 2017-04-12T18:09:20Z

docs/source/function_overloading.rst

-   my_abs = abs
-   my_abs(-2)      # 2 (int)
-   my_abs(-1.5)    # 1.5 (float)
+they still define a single runtime object. There is no multiple


s/multiple/automatic/

The user does implement dispatch in their implementation.

Agreed, and also: this is single dispatch rather than multiple dispatch, since only one argument determines the implementation. But the sentence should apply to both single and multiple dispatch of course.

sixolet · 2017-04-12T18:10:02Z

docs/source/function_overloading.rst

-   my_abs(-2)      # 2 (int)
-   my_abs(-1.5)    # 1.5 (float)
+they still define a single runtime object. There is no multiple
+dispatch happening, and you must manually handle the different types


"manually handle the different types in the implementation"

sixolet · 2017-04-12T18:10:35Z

docs/source/function_overloading.rst

+            else:
+                assert False, "Unsupported argument %r" % (index,)
+
+But this is a little loose, as it implies that when you put in an


s/a little/too/

sixolet · 2017-04-12T18:12:05Z

docs/source/function_overloading.rst

+            pass  # Don't put code here
+
+        # All overloads and the implementation must be adjacent
+        # in the source file, and overload order may matter.


Consider explaining how overload order matters -- without doing so it feels like a warning against using overloading, because stuff you don't understand might happen.

See #1270 (comment) for some background.

sixolet · 2017-04-12T18:12:33Z

docs/source/function_overloading.rst

+        def __getitem__(self, index: slice) -> Sequence[T]:
+            pass  # Don't put code here
+
+        # Actual implementation goes last, without @overload.


s/Actual/The/

sixolet · 2017-04-12T18:16:11Z

docs/source/function_overloading.rst

+            elif isinstance(index, slice):
+                ...  # Return a sequence of Ts here
+            else:
+                assert False, "Unsupported argument %r" % (index,)


raise TypeError("Unsupported index type '%s'" % index.__class__.__name__) or something like that is closer to what Python does in the builtin types.

sixolet · 2017-04-12T18:17:01Z

docs/source/function_overloading.rst

-yet) using the ``@overload`` decorator. For example, we can define an
-``abs`` function that works for both ``int`` and ``float`` arguments:
+Sometimes the types in a function depend on each other in ways that
+can't be captured with a simple ``Union``.  For example, the


sixolet · 2017-04-12T18:26:49Z

docs/source/function_overloading.rst

+
+But this is a little loose, as it implies that when you put in an
+``int`` you might sometimes get out a single item or sometimes a
+sequence.  To capture a constraint such as a return type that depends


It seems like your sentence structure here is a bit convoluted, and it might do to mention a type variable as another option here -- it's preferable when it's possible. Perhaps:

"The return type depends on the parameter type in a way that can't be expressed by a type variable. We can use overloading (link) to give the same function multiple type annotations (signatures) and accurately describe the function's behavior."

Or something -- wordsmithing is hard. My confidence that this version is better than yours is only about 70%.

gvanrossum · 2017-04-12T19:20:25Z

OK, how about now?

sixolet

I like it!

gvanrossum · 2017-04-12T19:38:59Z

Thanks @sixolet and @jkleint!

pkch · 2017-04-12T19:28:41Z

docs/source/function_overloading.rst

+                ...  # Return a sequence of Ts here
+            else:
+                assert False, "Unsupported argument %r" % (index,)
+


Maybe just inherit from Generic[T]? Otherwise, this code would fail with Signature of "__getitem__" incompatible with supertype "Sequence".

Well, that's kind of the point (though I agree it's pretty implicit here).

pkch · 2017-04-12T19:43:35Z

docs/source/function_overloading.rst

+            pass  # Don't put code here
+
+        # Actual implementation goes last, without @overload.
+        # It may or may not have type hints; if it does,


See #3160 for my concerns with both untyped and typed implementation. Maybe worth warning in the docs that untyped definitions result in the assumption of Any for each of the arguments (at least at the moment) -- that's if the body is even checked at all.

pkch · 2017-04-12T19:53:05Z

docs/source/function_overloading.rst

-yet) using the ``@overload`` decorator. For example, we can define an
-``abs`` function that works for both ``int`` and ``float`` arguments:
+Sometimes the types in a function depend on each other in ways that
+can't be captured with a simple ``Union``.  For example, the


maybe "can't be captured with a Union or generics"?

pkch · 2017-04-12T20:02:31Z

docs/source/function_overloading.rst

+            pass  # Don't put code here
+
+        # All overloads and the implementation must be adjacent
+        # in the source file, and overload order may matter.


See #1270 (comment) for some background.

pkch · 2017-04-12T20:26:44Z

docs/source/function_overloading.rst

-   my_abs(-2)      # 2 (int)
-   my_abs(-1.5)    # 1.5 (float)
+they still define a single runtime object. There is no multiple
+dispatch happening, and you must manually handle the different types


Perhaps add that using @functools.singledispatch with @overloaded is not yet supported.

Actually, @overload is not limited to a single argument, and at the type system level you can totally express multi-dispatch with it.

pkch · 2017-04-12T20:28:03Z

docs/source/function_overloading.rst

-   my_abs = abs
-   my_abs(-2)      # 2 (int)
-   my_abs(-1.5)    # 1.5 (float)
+they still define a single runtime object. There is no multiple


Agreed, and also: this is single dispatch rather than multiple dispatch, since only one argument determines the implementation. But the sentence should apply to both single and multiple dispatch of course.

gvanrossum · 2017-04-12T21:35:32Z

Since I already landed this version, feel free to submit a PR with proposed improvements. (Though I will be on vacation through Monday.)

jkleint and others added 2 commits April 12, 2017 10:33

Show how to @overload function annotations in user code

7c9d8aa

The docs say `@override` doesn't work in user code, but it seems to work in mypy 0.470. The update may be waiting on #2603, but that PR does not seem to include doc updates, so feel free to put this patch in that PR.

Reformat and update text of comments

4fa1387

gvanrossum mentioned this pull request Apr 12, 2017

Docs: show how to @overload function annotations in user code #2792

Closed

sixolet reviewed Apr 12, 2017

View reviewed changes

Wordsmithing; make examples compile

beebf1f

sixolet approved these changes Apr 12, 2017

View reviewed changes

gvanrossum merged commit 01bb4c1 into master Apr 12, 2017

gvanrossum deleted the overload-docs branch April 12, 2017 19:38

pkch reviewed Apr 12, 2017

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Overload docs #3159

Overload docs #3159

gvanrossum commented Apr 12, 2017

sixolet left a comment

sixolet Apr 12, 2017

pkch Apr 12, 2017

sixolet Apr 12, 2017

sixolet Apr 12, 2017

sixolet Apr 12, 2017

pkch Apr 12, 2017

sixolet Apr 12, 2017

sixolet Apr 12, 2017

sixolet Apr 12, 2017

sixolet Apr 12, 2017

gvanrossum commented Apr 12, 2017

sixolet left a comment

gvanrossum commented Apr 12, 2017

pkch Apr 12, 2017

gvanrossum Apr 12, 2017

pkch Apr 12, 2017 •

edited

Loading

pkch Apr 12, 2017 •

edited

Loading

pkch Apr 12, 2017

pkch Apr 12, 2017

gvanrossum Apr 12, 2017

pkch Apr 12, 2017

gvanrossum commented Apr 12, 2017

Overload docs #3159

Overload docs #3159

Conversation

gvanrossum commented Apr 12, 2017

sixolet left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gvanrossum commented Apr 12, 2017

sixolet left a comment

Choose a reason for hiding this comment

gvanrossum commented Apr 12, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pkch Apr 12, 2017 • edited Loading

Choose a reason for hiding this comment

pkch Apr 12, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gvanrossum commented Apr 12, 2017

pkch Apr 12, 2017 •

edited

Loading

pkch Apr 12, 2017 •

edited

Loading